Add trace correlation, breadcrumbs, and structured logging to Sentry sink

Summary

Adds observability features to @logtape/sentry for distributed systems debugging:

• Automatic trace correlation (trace_id/span_id from active spans)
• Optional breadcrumbs (debugging context trail)
• Configurable event levels
• Structured logging support (Sentry Logs API v9.41.0+)
• beforeSend hook for filtering/transformation
• Modern Sentry v8+ API pattern

Impact: ~270 LOC, 100% backward compatible, zero new dependencies

Why

The current @logtape/sentry integration (v1.1.x) works correctly but lacks observability features needed for distributed systems. When using LogTape with Sentry's tracing and performance monitoring, there's no way to correlate logs with traces, no debugging context trail via breadcrumbs, and messages with dynamic values create separate issues instead of grouping together.

This PR addresses these gaps while maintaining backward compatibility and cross-runtime support.

Compliance with Sentry Guidelines

This implementation follows official Sentry SDK development guidelines:

Uses Global Functions (Not Multiple Clients)

Following Sentry Best Practices, which state:

"Creating multiple Sentry clients is not recommended in general, as it can lead to unexpected behavior."

The sink uses global Sentry functions (captureMessage, captureException, getActiveSpan) instead of client instances. The v1.1.x client-based pattern is deprecated but remains functional for backward compatibility.

Logging Protocol Compliance

Implements features from Sentry SDK Logging Protocol:

• Trace Association: Automatically captures trace_id/span_id from active spans (lines 304-312)
• enableLogs Support: Auto-detects SDK 9.41.0+ and enableLogs: true configuration (lines 327-340)
• beforeSend Hook: Provides log filtering/transformation capability (lines 283-286)
• Default Attributes: Includes sentry.origin, category, timestamp (lines 296-301)

JavaScript Logging Standards

Meets requirements from Sentry JavaScript Logs Documentation:

• Minimum SDK version 9.41.0 for structured logging
• Graceful degradation for older SDK versions
• Proper log level mapping
• Automatic attribute enrichment

Feature Comparison

Comparison with other Sentry logging integrations:

Reference: Based on official Pino transport and community Winston transports.

What Changed

1. Automatic Trace Correlation (lines 304-312)

Captures trace_id, span_id, and parent_span_id from active Sentry spans. Always enabled with zero overhead if no active span exists. Uses Sentry v8+ getActiveSpan() API.

2. Optional Breadcrumbs (lines 315-324)

Adds logs as breadcrumbs to provide debugging context trail. Opt-in via enableBreadcrumbs: true.

getSentrySink({ enableBreadcrumbs: true });

3. Structured Logging Support (lines 327-340)

Automatic support for Sentry's Logs API (v9.41.0+). Users enable it in their Sentry config:

Sentry.init({ dsn: "...", enableLogs: true });

Uses _INTERNAL_captureLog (same approach as official Pino transport). Public wrapper APIs are in development (#15717).

Note: The official Pino transport only supports structured logging. This PR adds trace correlation, breadcrumbs, message grouping, and events support.

4. Enhanced Event Capture (lines 343-358)

Configurable event levels with special error handling. If log includes error property with Error instance, uses captureException for better stack traces.

getSentrySink({
  captureAsEvents: ["error", "fatal"],
  beforeSend: (record) => record  // Optional filter
});

5. Modern Sentry v8+ API Pattern (lines 272-278)

Uses global functions instead of client instances, following Sentry Best Practices:

// v1.2.0 (recommended)
getSentrySink();

// v1.1.x (deprecated but still works)
getSentrySink(getClient());

6. Additional Enhancements

• Enriched attributes: Adds sentry.origin, category, timestamp
• Level mapping: Consistent across events, breadcrumbs, and logs
• ParameterizedString: Preserves template structure for message grouping
• Error handling: Sink never throws

API

export interface SentrySinkOptions {
  enableBreadcrumbs?: boolean;      // Default: false
  captureAsEvents?: string[];       // Default: ["error", "fatal"]
  beforeSend?: (record: LogRecord) => LogRecord | null;
}

export function getSentrySink(
  optionsOrClient?: SentrySinkOptions | SentryInstance
): Sink

Backward compatibility: Existing code continues to work unchanged. Client parameter shows deprecation warning but remains functional.

Impact

• Logs automatically correlate with traces when using Sentry performance monitoring
• Breadcrumb trail shows what happened before errors
• Messages with dynamic values group correctly in Sentry UI
• No breaking changes; all existing LogTape + Sentry setups continue to work
• Cross-runtime support maintained for Deno, Node.js, Bun, browsers, and edge functions

Quality

• Type checking passes (deno check)
• Linting passes (deno lint)
• Formatting passes (deno fmt)
• Manual testing with real Sentry project (verified breadcrumbs, trace correlation, structured logs)
• Verified across Sentry SDK versions: v8.0, v9.41, v10.16
• Verified across runtimes: Node.js, Deno
• No unit tests added (following existing @logtape/sentry pattern - Sentry SDK difficult to mock meaningfully)

Files Changed

M  packages/sentry/src/mod.ts          (+342 lines - implementation)
M  packages/sentry/README.md           (minimal README)
M  docs/manual/sinks.md                (+243 lines - comprehensive documentation)
M  packages/sentry/deno.json           (version bump prep)
M  packages/sentry/package.json        (dependencies)
M  CHANGES.md                          (changelog)
M  deno.lock                           (dependency lock)
M  pnpm-lock.yaml                      (npm lock)

Dependencies: None added. Uses existing @sentry/core and @logtape/logtape.

Questions for Review

1. Should breadcrumbs default to true or false? (Currently false to avoid noise)